---
title: SAIF.Business.View.Policy architecture
summary: Architectural responsibilities, boundaries, and interaction patterns for the read-only policy-view and policy-authorization component.
status: draft
owner: SAIF Claims BOF team
last_reviewed: 2026-08-21
library: SAIF.Business.View.Policy
reference_type: embedded
---

# SAIF.Business.View.Policy architecture

`SAIF.Business.View.Policy` is a mid-tier, read-only VB.NET business-object component that assembles
a consolidated "policy header" view (policy data, address, agency, MCO, team assignments, trading-as
names, affiliations, payroll class info) and provides the central policy-authorization gate
(`clsPolicySecurity`) used by the Claims Legal front end. Every business object in this library
inherits from the `SAIF.Framework.Core` object/collection base classes† and is retrieved exclusively
through Oracle stored procedures/inline SQL (with one authorization-only path against a secondary
SQL Server BDS database).

## Responsibilities
- Aggregate a policy's "view" data — header, address, agency/agent, MCO assignment, team assignment
  roster, trading-as names, affiliated policies, and payroll class info — behind `clsPolicyData` as the
  principal entry point.
- Enforce policy-level authorization via `clsPolicySecurity.IsPolicyValidForUser(...)`, applying a
  global secure-policy AD-resource gate followed by per-user-type ownership/scope rules (agent,
  policyholder, group, loss-control, auditor, employee/MCO/med-provider/bookkeeper).
- Resolve policy-to-policy associations (manual affiliation, wrapup, leasing, sub-account, state
  agency, experience/discount combination) through `clsAssociationTypeCode` and the
  `Associations\` factory classes.
- Provide read-only data retrieval only — every `CreateSQL`/`InsertSQL`/`UpdateSQL`/`DeleteSQL`
  override across the 16 `IBusinessCriteria` objects returns empty/throws, confirming this library
  performs no writes.

## Component boundaries
- **Policy header aggregation** (`clsPolicyData`, `clsPolicyPeriod`, `clsPolicyPeriodCollection`) —
  owns the central policy view object and lazily loads related sub-objects (gaps, waiver flag, view
  detail) on demand.
- **Address/contact** (`clsPolicyAddress`, inherits `clsAddress`†) — policy/claim/policyholder
  contact and address, including a lazily-loaded "Officer of Notice" lookup built via inline SQL
  against `BUSINESS_AFFILIATE`/`AFFILIATE`.
- **Agency/MCO/team assignment** (`clsAgency`, `clsPolicyMCO(Collection)`, `clsMCOCollection`,
  `clsTeamAssignment(Collection)`) — supporting contact and assignment roster data, with demo-user
  data masking applied in several classes.
- **Association resolution** (`Associations\clsAssociationTypeCode(Collection)`,
  `clsPolicyAssociation`, `clsPolicyAssociationFactory` factories, legacy `PolicyAssociations.vb`) —
  translates policy-association type codes and produces `IPolicyHeaderAssociation` lists.
- **Authorization** (`clsPolicySecurity`) — a plain (non-`clsBusinessBase`) class that is the sole
  security boundary in this library; it is constructed from a `clsSecurityPrincipal` and an
  `IDataPortalInfo`, and internally builds a second, SQL-Server-backed `IDataPortalInfo` (`DPISql`)
  used only for group/loss-control/agent book-of-business stored-procedure lookups.
- **Supporting reference/search objects** (`clsTradingAs(Collection)`, `clsNonEmployerAccount`,
  `clsPayrollClassInfo(Collection)`, `clsPolicySearch`, `PolicyStatusEnums`, typed DataSet
  `Institutions`) — self-contained reference and search-result value types.

## Interaction model
- Consumers (the Claims Legal front end and sibling business libraries) obtain a populated
  `clsPolicyData` via one of `GetPolicyData`'s four overloads, then navigate to its aggregated
  sub-objects (address, agency, team assignments, associations) rather than retrieving them
  independently.
- All retrieval-oriented business objects follow the standard SAIF BOF `Criteria` +
  `DataAccessLayer.RetrieveObject` pattern inherited from `clsBusinessBase`†/
  `clsBusinessCollectionBase`†: a `Criteria.RetrieveSQL` (or ad hoc method) supplies the SQL/procedure
  call, and `BeforeRetrieve`/`AfterRetrieve` hooks populate the object from the returned cursor.
- `clsPolicySecurity` sits alongside, not inside, the `clsBusinessBase` object graph — it is called by
  front-end/caller code to gate access to an already-retrieved (or about-to-be-retrieved)
  `clsPolicyData` instance, and separately produces book-of-business policy lists per user type.
- Data access is split by database: the Oracle primary database serves nearly all policy-view
  retrieval (via `pk72846_view_policy.*`, `pk73094_policy_data.getpolicy`, and related packages,
  plus a small amount of inline SQL), while a secondary SQL Server BDS connection, built from
  Environment API settings (`BDS_USER`, `bdsDatabase`, `BDS_DATABASENAME`) inside
  `clsPolicySecurity.Initialize()`, serves only group/loss-control/agent authorization
  stored-procedure calls.

## Design constraints
- The library is strictly read-only; no create/update/delete SQL path is implemented anywhere in
  its 16 business objects.
- `clsPolicySecurity` is a hand-written, non-attribute-based authorization class rather than a
  declarative/attribute-driven mechanism — all per-user-type rules are expressed as `Select Case`
  logic over `clsUserType.UserTypes`.
- The primary `IDataPortalInfo` (`DPI`) consumed by most objects is injected by the caller and its
  underlying database engine cannot be determined from within this library*; only the secondary
  SQL Server BDS connection used by `clsPolicySecurity` is self-configured.
- Several classes (`clsMCOCollection` vs. `clsPolicyMCOCollection`) appear to duplicate retrieval of
  the same stored procedure, suggesting legacy/duplicate code paths rather than a single canonical
  MCO retrieval component*.
- `clsPolicyData.AffiliateTypes` is `<Obsolete>`, superseded by the `Associations`/
  `clsAssociationTypeCode` model, but remains present for backward compatibility.

## Architecture diagram
The following diagram shows the high-level component boundaries and their relationship to the
inherited framework base classes and the two backing databases.

```mermaid
flowchart TD
	Caller[Claims Legal front end /<br>sibling business libraries] --> PD[clsPolicyData<br>policy header aggregate]
	Caller --> Sec[clsPolicySecurity<br>authorization gate]
	PD --> Addr[clsPolicyAddress]
	PD --> Agency[clsAgency]
	PD --> MCO[clsPolicyMCOCollection /<br>clsMCOCollection]
	PD --> Team[clsTeamAssignmentCollection]
	PD --> Assoc[Associations:<br>clsAssociationTypeCode,<br>clsPolicyAssociationFactory]
	PD --> Period[clsPolicyPeriodCollection]
	Sec --> PD
	Sec --> DPISql[Secondary SQL Server DPI<br>BDS group/book-of-business lookups]
	PD --> Base[clsBusinessBase /<br>clsBusinessCollectionBase†]
	Addr --> AddrBase[clsAddress†]
	PD --> Oracle[(Oracle primary DB<br>pk72846_view_policy, pk73094_policy_data)]
	DPISql --> SQLServer[(SQL Server BDS DB<br>cp_* stored procedures)]
```

## Sequence diagram
The following diagram shows the typical flow when a caller retrieves and authorizes a policy view.

```mermaid
sequenceDiagram
	participant Caller as Claims Legal front end
	participant PolicySecurity as clsPolicySecurity
	participant PolicyData as clsPolicyData
	participant Oracle as Oracle primary DB
	participant SQLServer as SQL Server BDS DB

	Caller->>PolicyData: GetPolicyData(DPI, policyNum, accessLevel)
	PolicyData->>Oracle: pk73094_policy_data.getpolicy (RetrieveSQL)
	Oracle-->>PolicyData: policy header cursor
	Caller->>PolicySecurity: IsPolicyValidForUser(policyData)
	PolicySecurity->>PolicySecurity: check SAIFpolicyInfo AD resource (secure policies)
	PolicySecurity->>SQLServer: cp_policy_in_group / cp_claimprofile_get_group_policy_list (Group/Agent paths)
	SQLServer-->>PolicySecurity: membership result
	PolicySecurity-->>Caller: access granted/denied
	Caller->>PolicyData: navigate Address / Agency / TeamAssignments / Associations
```

## Related documentation
- [Index](index.md)
- [Overview](overview.md)
- [Dependencies](dependencies.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [Database tables](database-tables.md)
- [Security and authorization](security-authorization.md)
- [SQL catalog](sql/index.md)
- [API reference](api/index.md)

> **Note:** Statements marked with `†` are derived from dependency library
> documentation via the Legends CLI. Statements marked with `*` were inferred
> from code structure or contextual evidence. Statements marked with `**` could
> not be confirmed; treat as unknown until verified.

## Sources
- `SAIF.Business.View.Policy\clsPolicyData.vb`
- `SAIF.Business.View.Policy\clsPolicySecurity.vb`
- `SAIF.Business.View.Policy\clsPolicyAddress.vb`
- `SAIF.Business.View.Policy\SAIF.Business.View.Policy.vbproj`